/*
 * Licensed to the Apache Software Foundation (ASF) under one or more
 * contributor license agreements.  See the NOTICE file distributed with
 * this work for additional information regarding copyright ownership.
 * The ASF licenses this file to You under the Apache License, Version 2.0
 * (the "License"); you may not use this file except in compliance with
 * the License.  You may obtain a copy of the License at
 *
 *    http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

package org.apache.flink.connector.jdbc.internal.executor;

import org.apache.flink.annotation.Internal;
import org.apache.flink.connector.jdbc.converter.JdbcRowConverter;
import org.apache.flink.connector.jdbc.statement.FieldNamedPreparedStatement;
import org.apache.flink.connector.jdbc.statement.StatementFactory;
import org.apache.flink.table.data.RowData;

import java.sql.Connection;
import java.sql.ResultSet;
import java.sql.SQLException;
import java.util.Arrays;
import java.util.function.Function;

import static org.apache.flink.util.Preconditions.checkNotNull;

/**
 * {@link JdbcBatchStatementExecutor} that provides upsert semantics by updating row if it exists
 * and inserting otherwise. 
 * {@link JdbcBatchStatementExecutor}，通过更新行（如果存在）并插入否则提供更新插入语义。
 *
 * Only used in Table/SQL API.  仅在表/SQL API 中使用。
 */
@Internal
public final class TableInsertOrUpdateStatementExecutor
        implements JdbcBatchStatementExecutor<RowData> {

    private final StatementFactory existStmtFactory;
    private final StatementFactory insertStmtFactory;
    private final StatementFactory updateStmtFactory;

    private final JdbcRowConverter existSetter;
    private final JdbcRowConverter insertSetter;
    private final JdbcRowConverter updateSetter;
    
    // R apply(T t)是一个函数式接口 Function<T, R>中定义的抽象方法，
    // 它接收一个类型为 T的参数，并返回一个类型为 R的值。
    //该方法的作用是将参数t转换为类型为 R的值。
    private final Function<RowData, RowData> keyExtractor;

    private transient FieldNamedPreparedStatement existStatement;
    private transient FieldNamedPreparedStatement insertStatement;
    private transient FieldNamedPreparedStatement updateStatement;

    /**
     * 这段代码是Java的构造函数，它接受多个参数，
     * 
     * @param existStmtFactory：表示存在的语句工厂；
     * @param insertStmtFactory：表示插入的语句工厂；
     * @param updateStmtFactory：表示更新的语句工厂；
     * @param existSetter：表示存在的 JDBC行转换器；
     * @param insertSetter：表示插入的 JDBC行转换器；
     * @param updateSetter：表示更新的 JDBC行转换器；
     * @param keyExtractor：表示键提取函数。
     */
    public TableInsertOrUpdateStatementExecutor(
            StatementFactory existStmtFactory,
            StatementFactory insertStmtFactory,
            StatementFactory updateStmtFactory,
            JdbcRowConverter existSetter,
            JdbcRowConverter insertSetter,
            JdbcRowConverter updateSetter,
            Function<RowData, RowData> keyExtractor) {
        this.existStmtFactory = checkNotNull(existStmtFactory);
        this.insertStmtFactory = checkNotNull(insertStmtFactory);
        this.updateStmtFactory = checkNotNull(updateStmtFactory);
        this.existSetter = checkNotNull(existSetter);
        this.insertSetter = checkNotNull(insertSetter);
        this.updateSetter = checkNotNull(updateSetter);
        this.keyExtractor = keyExtractor;
    }

    /**
     *  prepareStatements方法的实现，它用于准备语句对象。
     *  该方法接收一个 Connection对象作为参数，用于创建语句对象。
     *  
     * @param connection
     * @throws SQLException
     */
    @Override
    public void prepareStatements(Connection connection) throws SQLException {
        //首先，使用existStmtFactory、insertStmtFactory和updateStmtFactory
        // 分别调用createStatement(connection)方法，创建对应的语句对象。
        existStatement = existStmtFactory.createStatement(connection);
        insertStatement = insertStmtFactory.createStatement(connection);
        updateStatement = updateStmtFactory.createStatement(connection);
    }

    /**
     * addToBatch是一个方法，用于将一行数据添加到批处理中。
     * 该方法接收一个参数record，表示要添加到批处理的数据行。
     * 
     * @param record
     * @throws SQLException
     */
    @Override
    public void addToBatch(RowData record) throws SQLException {
        //首先，使用 keyExtractor函数将 record转换为主键行数据。
        //然后，调用 processOneRowInBatch方法，
        //将主键行和数据行作为参数传递给它，以进行批处理的处理。
        processOneRowInBatch(keyExtractor.apply(record), record);
    }

    /**
     * processOneRowInBatch是一个方法，用于在批处理中处理一行数据。
     * 
     * @param pk：表示主键行；
     * @param row：表示数据行。
     *           
     * @throws SQLException
     */
    private void processOneRowInBatch(RowData pk, RowData row) throws SQLException {
        //首先，通过调用exist(pk)方法判断主键行是否存在。
        if (exist(pk)) {
            // 如果主键行存在，则使用updateSetter将数据行的值设置到updateStatement中，
            updateSetter.toExternal(row, updateStatement);
            // 并将该更新语句添加到批处理中。
            updateStatement.addBatch();
        } else {
            //如果主键行不存在，则使用insertSetter将数据行的值设置到insertStatement中，
            insertSetter.toExternal(row, insertStatement);
            // 并将该插入语句添加到批处理中。
            insertStatement.addBatch();
        }
    }

    /**
     * exist是一个方法，用于判断数据库中是否存在指定的主键行。
     * @param pk：表示主键行的数据。
     * @return
     * @throws SQLException
     */
    private boolean exist(RowData pk) throws SQLException {
        //首先，使用 existSetter 将主键行的值设置到 existStatement 中。
        existSetter.toExternal(pk, existStatement);
        //然后，执行查询语句，获取查询结果集。
        try (ResultSet resultSet = existStatement.executeQuery()) {
            //如果查询结果集中存在数据，则说明主键行存在，返回 true。
            //否则，说明主键行不存在，返回false。
            return resultSet.next();
            //当调用 next()方法时，如果结果集中存在下一行数据，则方法返回 true;
            //不存在时，则返回 false
        }
    }

    /**
     *  executeBatch方法的实现，它用于执行批处理操作。
     *  该方法会依次执行更新语句和插入语句的批处理。
     *  
     * @throws SQLException
     */
    @Override
    public void executeBatch() throws SQLException {

        //首先，调用updateStatement.executeBatch()方法执行更新语句的批处理。
        updateStatement.executeBatch();
        //然后，调用insertStatement.executeBatch()方法执行插入语句的批处理。
        insertStatement.executeBatch();
    }

    /**
     *  closeStatements方法的实现，它用于关闭语句对象。
     *  该方法会遍历存在的语句对象列表，并逐个关闭它们。
     *  
     * @throws SQLException
     */
    @Override
    public void closeStatements() throws SQLException {
        //首先使用 Arrays.asList()方法
        //创建一个包含 existStatement、insertStatement和 updateStatement的列表。
        //然后，使用 for-each循环遍历列表中的每个语句对象 s。
        for (FieldNamedPreparedStatement s :
                Arrays.asList(existStatement, insertStatement, updateStatement)) {
            //在循环中，检查语句对象 s是否为 null，
            if (s != null) {
                // 如果不为 null，则调用 s.close() 方法关闭语句对象。
                s.close();
            }
        }
    }
}
